'\"macro stdmacro
.\"
.\" Copyright (c) 2009 Ken McDonell.  All Rights Reserved.
.\"
.\" This program is free software; you can redistribute it and/or modify it
.\" under the terms of the GNU General Public License as published by the
.\" Free Software Foundation; either version 2 of the License, or (at your
.\" option) any later version.
.\"
.\" This program is distributed in the hope that it will be useful, but
.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
.\" or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
.\" for more details.
.\"
.\"
.TH PMLOADDERIVEDCONFIG 3 "" "Performance Co-Pilot"
.SH NAME
\f3pmLoadDerivedConfig\f1 \- load derived metric definitions from files
.SH "C SYNOPSIS"
.ft 3
#include <pcp/pmapi.h>
.sp
int pmLoadDerivedConfig(char *\fIpath\fP);
.sp
cc ... \-lpcp
.ft 1
.SH DESCRIPTION
Derived metrics may be used to extend the available metrics with
new (derived) metrics using simple arithmetic expressions.
The definitions of these metrics can be persisted and loaded
programatically by monitor tools using
.BR pmLoadDerivedConfig .
.PP
The
.I path
parameter defines a colon separated list of files and/or
directories (the syntax is the same as for the
.B $PATH
variable for
.BR sh (1)),
from which derived metric specifications are to be sourced.
The
.I path
components are expanded into a list of files as follows: if a component
is a file, then that file is added to the list, else if a component
is a directory then recursive descent is used to enumerate all
files below that directory and these are added to the list.
Each file in the resulting list is parsed in order, and according to
the derived metrics syntax described below.
.PP
Each line of the file(s) identified by
.I path
is either a comment line (with a ``#'' in the first position of the line)
or the declaration of a derived performance metric, specified as:
.IP * 2n
the name of the derived metric, using the same ``dot notation'' syntax
that is used for PCP performance metrics, see
.BR PCPIntro (1)
and
.BR PMNS (5).
.PD 0
.IP * 2n
an equals sign (``='')
.IP * 2n
a valid expression for a derived metric, as described in
.BR pmRegisterDerived (3).
.PD
.PP
For each line containing a derived metric definition,
.BR pmRegisterDerived (3)
is called to register the new derived metric.
.PP
Once a derived metric has been declared, it may be assigned additional
attributes with a line of the form:
.IP * 2n
the name of the derived metric,
.PD 0
.IP * 2n
a left parenthesis, an
.I attribute
.I type
and a right parenthesis,
.IP * 2n
an equals sign (``=''),
.IP * 2n
an
.I attribute
.IR value .
.PD
.PP
Currently,
.I attribute
.I type
may be either
.B oneline
or
.B helptext
to designate the ``one line'' or expanded help text to be associated with
the derived metric, see
.BR pmLookupText (3).
.PP
The
.I attribute
.I value
may be either arbitrary text following the ``='' and ending at the end
of the line, else a string enclosed in either single quotes (') or
double quotes (").  In the latter case, the
.I attribute
.I value
may span multiple lines, and a simple escape mechanism is supported,
namely for any character ``x'', ``\ex'' is replaced by ``x'' (this
allows quotes to be escaped within a string, for example), and there
is a special case when the ``\e'' comes at the end of the line in
which case the following newline is not included in the
.I attribute
.IR value .
.PP
Outside of
.I attribute
.IR values ,
white space is ignored in the lines, and blank lines are ignored altogether.
.PP
Because
.B pmLoadDerivedConfig
may process many files, each of which may contain many derived metric
specifications, it is not possible to provide a specific error
status on return.
Hence the result from
.B pmLoadDerivedConfig
will be the number of derived metrics successfully loaded from
files on the given
.IR path .
Catastrophic errors such as not being able to open one of the
files on the given
.I path
will cause an immediate return with a negative return value
that can be passed to
.BR pmErrStr (3)
to obtain the associated error message.
.PP
When errors are encountered in the derived metric specifications
diagnostic messages are generated by
.BR pmRegisterDerived (3)
and displayed via
.BR pmprintf (3).
.SH EXAMPLE
.nf
# sample derived metric definitions
bad_in_pkts = network.interface.in.errors + network.interface.in.drops
# note the following would need to be on a single line ...
disk.dev.read_pct = 100 * delta(disk.dev.read) /
            (delta(disk.dev.read) + delta(disk.dev.write))
disk.dev.read_pct(oneline) = percentage of disk reads
disk.dev.read_pct(helptext) = '\e
Percentage of disk reads compared to the total number of
disk reads and disk writes.'
.fi
.SH SEE ALSO
.BR sh (1),
.BR PCPIntro (1),
.BR PMAPI (3),
.BR pmLookupText (3),
.BR pmRegisterDerived (3),
.BR pmprintf (3)
and
.BR PMNS (5).
